甚麼是API ?

API全名為Application Programming Interface，它定義多個軟體中介之間的互動，以及可以進行的呼叫（call）或請求（request）的種類，如何進行呼叫或發出請求，，讓不同應用程式之間的整合和溝通變得更加容易，進而達到開發成本的降低。
以生活中的例子舉例，我們在訂餐的時候，我們只需要跟櫃台說我們想點哪份餐點，最後我們就會獲得餐點，但我們並不需要了解或知道怎麼出餐製作的過程，這就是API的好處。

而在前後端之間的溝通最重要的也就是Request和Response了 !!!

甚麼是RESTful API ?

REST (Representational State Transfer) 是一種依照資源來設計 API 界面的一種架構，透過架構來定義 API 的傳入和傳出該如何去組成和設計，而RESTful API 是一種能讓兩個電腦系統用來安全地透過網際網路交換資訊的介面。大多數商業應用程式必須與其它內部和第三方應用程式溝通，以執行各種任務。

RESTful API的定義

• 名詞:用來定義傳輸資源的URL。
• 動詞:對Nouns名詞的操作方式，也就是HTTP Methods。
• Content Types：資源的呈現方式有許多種，最常使用的就是JSON或是XML格式了。

RESTful API Methods

• GET : 通常用於取得資料或是狀態
• POST : 用於新增資料的部分
• PUT : 更新資源
• DELETE : 刪除資源

REST 架構的原則

• 統一介面:具有HTTP Methods、route與明確定義的請求與響應資料結構
• 無狀態:Server與Client不儲存連接歷史，每個請求都是獨立的。

HTTP STATUS CODE 定義

我們這邊列出常見的一些status :

• 200：一般成功回應
• 201：POST 方法成功回應
• 204 : 有成功回應，但沒有回傳的內容
• 400：伺服器無法處理的錯誤請求
• 401 : Unauthorized 回應狀態碼表示用戶端請求未完成，因為驗證身分失敗
• 404：找不到資源，Not Found
• 500 : Internal Server Error
• 503 Service Unavailable，表示伺服器現在非常的忙碌，沒有辦法正常的運作

只有2XX系列的是成功回應的status，其他皆為有錯誤的status

那這些部份我們跟Spring boot的Annotation怎麼對應呢 ?

HTTP Method對應Spring boot Annotation

GET: @GetMapping

POST: @PostMapping

PUT: @PutMapping

DELETE: @DeleteMapping

昨天我們已經有完成Get API，今天我們接著繼續實現剩下的method吧 ⭐️

實作 POST/book

POST /book 代表我們要新增一本書本資訊。

• Controller

    @PostMapping("book")
    public ResponseEntity<?> createBook(@RequestBody Book book) {
        ironService.createBook(book);
        return ResponseEntity.ok().body("OK");
    }

• Service

    @Transactional
    public void createBook(Book book) {
        bookRepo.save(book);
    }

我們接著就可以用POSTMAN來試試看了剛剛寫好的POST API !!

接著再查詢DB驗證結果，你是不是成功了呢 ?!

實作 PUT/book

PUT /book/{bookId} 代表我們要更新一本書本資訊。
那就拿剛剛前面新增的書本為例，我們要把name從TST更新成HELLO WORLD
這樣的話，我們要怎麼設計界面呢 ?

• Controller

    @PutMapping("book/{bookId}")
   public ResponseEntity<?> updateBook(@PathVariable("bookId") int bookId, @RequestBody Book book) throws BadRequestException {
       ironService.updateBook(bookId, book);
       return ResponseEntity.ok().body("UPDATE OK");
   }

我們會需要先找出需要更新的書本，會用他的唯一識別資訊查詢，接著再RequestBody帶入要更新的資訊

用POSTMAN試試看吧!

Body就是用JSON格式來寫要更新書本的內容，

{
   "author": "Winnie",
   "name": "HEELO WORLD",
   "bookId": 3
}

我們再去看看資料庫內容是否更新成功呢 ?!

那這樣Delete大家應該看著上面的範例後，也可以舉一反三了嗎

那我們明天就來教大家，如何直接快速生成API文件，讓你不用都只能用POSTMAN測試API吧 !!!!!

參考資料

• API維基百科
• 一文搞懂 Http Status Code，詳細解析 200、301、401、403、500、503